Crate libyml

LibYML (a fork of unsafe-libyaml)

This library is a fork of unsafe-libyaml, a version of libyaml translated from C to unsafe Rust with the assistance of c2rust.

This project, has been renamed to LibYML for simplicity and to avoid confusion with the original unsafe-libyaml crate which is now archived and no longer maintained.

Credits and Acknowledgements

This library is a fork of the excellent work done by David Tolnay and the maintainers of the unsafe-libyaml library.

LibYML has now evolved into a separate library with its own goals and direction in mind and does not intend to replace the original unsafe-libyaml crate.

If you are currently using unsafe-libyaml in your projects, we recommend carefully evaluating your requirements and considering the stability and maturity of the original library as well as looking at the features and improvements offered by other libraries in the Rust ecosystem.

I would like to express my sincere gratitude to David Tolnay and the unsafe-libyaml and libyaml maintainers for their valuable contributions to the Rust and C programming communities.

[dependencies]
libyml = "0.0.4"

Release notes are available under GitHub releases.

Rust Version Compatibility

This library is compatible with Rust 1.60 and above.

Features

• Serialization and Deserialization: LibYML provides easy-to-use APIs for serializing Rust structs and enums into YAML format and deserializing YAML data into Rust types.
• Custom Struct and Enum Support: The library allows you to work with custom structs and enums, enabling seamless serialization and deserialization of your own data types.
• Error Handling: LibYML provides comprehensive error handling mechanisms, including detailed error messages and the ability to handle and recover from parsing and emission errors.
• Streaming Support: The library supports streaming of YAML data, allowing you to efficiently process large YAML documents incrementally.
• Alias and Anchor Support: LibYML handles YAML aliases and anchors, enabling you to work with complex YAML structures that involve references and duplicated data.
• Tag Handling: The library provides support for custom tags, allowing you to serialize and deserialize YAML data with specific type information.
• Configurable Emitter: LibYML allows you to customize the emitter settings, such as indentation, line width, and scalar style, to generate YAML output according to your preferences.
• Extensive Documentation: The library comes with detailed documentation and examples, making it easy to get started and understand how to use its various features effectively.
• Safety and Efficiency: LibYML is designed with safety and efficiency in mind. It minimizes the use of unsafe code and provides an interface that helps prevent common pitfalls and errors.

Examples

To get started with LibYML, you can use the examples provided in the examples directory of the project.

LibYML provides a set of comprehensive examples to demonstrate its usage and capabilities. The examples cover various aspects of the library, including initializing and deleting parsers, setting input strings, memory management, string manipulation, and more.

To run the examples, clone the repository and navigate to the examples directory. Each example is contained in a separate file, focusing on specific functionalities or use cases.

For instance, to run all the example demonstrating the usage of the LibYML APIs, you can execute the following command:

cargo run --example example

The command will execute all the examples code, demonstrating all the features and use cases of the LibYML library.

Here are a few notable examples you can also run individually:

1) The apis Example

The api.rs file provides a set of low-level API functions for working with YAML data in the LibYML library. The apis example showcases the usage of these low-level APIs covering functions such as:

• yaml_parser_initialize - Initialize a YAML parser,
• yaml_parser_delete - Delete a YAML parser,
• yaml_parser_set_input_string - Set the input string for the parser,
• yaml_malloc - Allocate memory,
• yaml_realloc - Reallocate memory,
• yaml_free - Free memory,
• yaml_strdup - Duplicate a string,
• yaml_string_extend - Extend a string,
• yaml_string_join - Join strings,

You can run the apis example using the following command:

cargo run --example apis

License

MIT license, same as libyaml.

Re-exports

• pub use crate::api::yaml_alias_event_initialize;
• pub use crate::api::yaml_emitter_delete;
• pub use crate::api::yaml_emitter_initialize;
• pub use crate::api::yaml_emitter_set_break;
• pub use crate::api::yaml_emitter_set_canonical;
• pub use crate::api::yaml_emitter_set_encoding;
• pub use crate::api::yaml_emitter_set_indent;
• pub use crate::api::yaml_emitter_set_output;
• pub use crate::api::yaml_emitter_set_output_string;
• pub use crate::api::yaml_emitter_set_unicode;
• pub use crate::api::yaml_emitter_set_width;
• pub use crate::api::yaml_event_delete;
• pub use crate::api::yaml_mapping_end_event_initialize;
• pub use crate::api::yaml_mapping_start_event_initialize;
• pub use crate::api::yaml_parser_set_encoding;
• pub use crate::api::yaml_parser_set_input;
• pub use crate::api::yaml_parser_set_input_string;
• pub use crate::api::yaml_scalar_event_initialize;
• pub use crate::api::yaml_sequence_end_event_initialize;
• pub use crate::api::yaml_sequence_start_event_initialize;
• pub use crate::api::yaml_stream_end_event_initialize;
• pub use crate::api::yaml_stream_start_event_initialize;
• pub use crate::api::yaml_token_delete;
• pub use crate::decode::yaml_parser_delete;
• pub use crate::decode::yaml_parser_initialize;
• pub use crate::document::yaml_document_delete;
• pub use crate::document::yaml_document_get_node;
• pub use crate::document::yaml_document_get_root_node;
• pub use crate::document::yaml_document_initialize;
• pub use crate::loader::yaml_parser_load;
• pub use crate::yaml::YamlAliasDataT;
• pub use crate::yaml::YamlBreakT;
• pub use crate::yaml::YamlDocumentT;
• pub use crate::yaml::YamlEmitterStateT;
• pub use crate::yaml::YamlEmitterT;
• pub use crate::yaml::YamlEncodingT;
• pub use crate::yaml::YamlErrorTypeT;
• pub use crate::yaml::YamlEventT;
• pub use crate::yaml::YamlEventTypeT;
• pub use crate::yaml::YamlMappingStyleT;
• pub use crate::yaml::YamlMarkT;
• pub use crate::yaml::YamlNodeItemT;
• pub use crate::yaml::YamlNodePairT;
• pub use crate::yaml::YamlNodeT;
• pub use crate::yaml::YamlNodeTypeT;
• pub use crate::yaml::YamlParserStateT;
• pub use crate::yaml::YamlParserT;
• pub use crate::yaml::YamlReadHandlerT;
• pub use crate::yaml::YamlScalarStyleT;
• pub use crate::yaml::YamlSequenceStyleT;
• pub use crate::yaml::YamlSimpleKeyT;
• pub use crate::yaml::YamlStackT;
• pub use crate::yaml::YamlTagDirectiveT;
• pub use crate::yaml::YamlTokenT;
• pub use crate::yaml::YamlTokenTypeT;
• pub use crate::yaml::YamlVersionDirectiveT;
• pub use crate::yaml::YamlWriteHandlerT;

Modules

• api
  API module for LibYML
• decode
  Decode module for LibYML
• document
  Document module for LibYML
• externs
  Externs for libyaml
• internal
  Internal module for LibYML
• libc
  This module contains declarations for C library functions.
• loader
  Loader module for LibYML
• memory
  Memory module for LibYML
• string
  String module for LibYML
• success
  Success and Failure types for LibYML
• utils
  Macros module for LibYML
• yaml
  YAML API module for LibYML

Macros

• yaml_free
  Frees memory allocated by yaml_malloc! or yaml_realloc!.
• yaml_malloc
  Allocates memory using the system’s malloc function.
• yaml_realloc
  Reallocates memory using the system’s realloc function.
• yaml_strdup
  Duplicates a string using the system’s malloc function and manual copy.

Functions

• yaml_emitter_close^⚠
  Finish a YAML stream.
• yaml_emitter_dump^⚠
  Emit a YAML document.
• yaml_emitter_emit^⚠
  Emit an event.
• yaml_emitter_flush^⚠
  Flushes the buffer of the emitter and writes the content to the output stream.
• yaml_emitter_open^⚠
  Start a YAML stream.
• yaml_parser_parse^⚠
  Parse the input stream and produce the next parsing event.
• yaml_parser_scan^⚠
  Scan the input stream and produce the next token.